home *** CD-ROM | disk | FTP | other *** search
/ Greenhouse Effect Detection Expriment / NASA Greenhouse Effect Detection Expriment 1992 - Disc 2.iso / software / dos / cdf22pc / src / tools / curses / curses.man < prev    next >
Encoding:
Text File  |  1992-01-09  |  15.8 KB  |  299 lines
  1. CURSES(3)         MS-DOS Programmer's Manual        CURSES(3)
  2.  
  3. NAME
  4.    curses - screen/window management library
  5.  
  6. DESCRIPTION
  7.    Curses is a library of screen and window management routines. It is
  8.    modeled after the UNIX curses and ncurses libraries. Normally, programs
  9.    written for PCcurses should be easily ported to UNIX, and vice versa.
  10.  
  11.    To use the routines, the function initscr() must first be called. This
  12.    creates two 'windows' for the user: stdscr and curscr. Stdscr is the
  13.    default window for the user to make changes on, and curscr reflects the
  14.    current contents of the physical display screen. The user writes or
  15.    edits the stdscr window to his liking, then calls the refresh() function
  16.    to make curscr and the physical screen look like stdscr. When the user
  17.    program terminates, it should call the endwin() function to restore
  18.    things to normal.
  19.  
  20.    There are all sorts of window manipulation routines available to the
  21.    programmer: auxiliary windows may be created, edited, moved and deleted.
  22.    The terminal may be set in many different modes, output text may be
  23.    attributed with blink, blank, bold and reverse attributes. There are
  24.    window-specific printf- and scanf-like routines, routines for scrolling,
  25.    box-drawing, window overlaying, clearing routines etc. Curses also
  26.    handles terminal function keys, which is enables by calling the keypad()
  27.    function.
  28.  
  29.    The handling of character attributes is different on MGA, CGA and
  30.    Hercules adapters. The package has been tested with them all. EGA has
  31.    not been tested, but should also work except for special screen modes.
  32.  
  33.    For more and detailed information, see the library source codes. All
  34.    curses functions are preceded by a brief but complete description.
  35.  
  36. COMPILING
  37.    All programs that use curses facilities should include the file
  38.    <curses.h>, and during linking, the library ?curses.lib should be
  39.    specified to the linker ('?' is 's', 'c' 'm' or 'l' for small, compact,
  40.    medium or large memory model respectively).
  41.  
  42. FUNCTIONS
  43.    Below is a list over the available functions, together with a brief
  44.    description of what they do. In general, functions whose names start
  45.    with 'w' differ from the one without 'w' (like wmove vs. move) signify
  46.    that a specific window is used. Without a 'w', stdscr is implied. The
  47.    functions that start with 'mv' before the 'generic' function name
  48.    signify that a cursor motion should be made before the actual work. 'mv'
  49.    and 'w' combine as expected.
  50.  
  51.    Most routines that return an int will return the manifest constant ERR
  52.    if there is a failure during execution. Routines that return a char
  53.    actually return an int, so that ERR does not conflict with the character
  54.    code 0xff. All IBM PC characters from 0 to 0xff are allowed for usage
  55.    with curses. There are (non-portable) character output routines to write
  56.    the special IBM fonts for characters with ASCII code less than 0x20
  57.    (control characters).
  58.  
  59.    Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a
  60.    meaningful positive value if the operation is successful.
  61.  
  62.    The curses package uses some predefined types, variables and manifest
  63.    constants that are also available to the programmer. There are also a
  64.    few globally accessible variables that should not be touched by the
  65.    application program. Those untouchable variables have names starting
  66.    with an underscore (_) to avoid conflicts. The user-accessible types,
  67.    variables and constants are (there are a number of other constants
  68.    defining character attribute names and function key names - consult
  69.    <curses.h> for details):
  70.  
  71.    (manifest constants)
  72.  
  73.       TRUE                boolean true
  74.       FALSE               boolean false
  75.       ERR                 unsuccessful operation
  76.       OK                  successful operation
  77.  
  78.    (types)
  79.  
  80.       WINDOW              a window structure type
  81.       bool                boolean flag type
  82.  
  83.    (variables)
  84.  
  85.       WINDOW curscr       physical display image
  86.       WINDOW stdscr       default user drawing board
  87.       int    LINES        terminal height
  88.       int    COLS         terminal width
  89.  
  90.    The following is an alphabetical list of the curses functions, together
  91.    with their types, parameters and a short comment for each. Win is a
  92.    window; ch, l, r, t, b, tl, tr, bl and br are characters; buf is a
  93.    character buffer; attrs is an attribute bit map; bf is a boolean flag.
  94.    Note that `character' return values in this context usually can have 16
  95.    bits. Guaranteed portable functions (existing in Berkeley UNIX curses)
  96.    are marked with an asterisk (*):
  97.  
  98.  
  99. *  int   addch(ch)            put char in stdscr
  100.    int     addrawch(ch)       put raw char in stdscr
  101. *  int     addstr(str)        put string in stdscr
  102.    void    attroff(attrs)     clear attribute(s) in stdscr
  103.    void    attron(attrs)      add attribute(s) in stdscr
  104.    void    attrset(attrs)     set stdscr char attributes
  105.    int     baudrate()         dummy for compatibility
  106.    void    beep()             ring the bell
  107.    void    border(l,r,t,b,tl,tr,bl,br)    Set non-std box characters
  108. *  void    box(win,l,t)       box in a window, with given characters
  109. *  void    cbreak()           set terminal cbreak mode
  110. *  void    clear()            clear stdscr
  111. *  void    clearok(win,bf)    marks window for screen clear
  112. *  int     clrtobot()         clear end of stdscr
  113. *  int     clrtoeol()         clear end of line in stdscr
  114. *  void    crmode()           set terminal cbreak mode
  115.    void    cursoff()          turns off hardware cursor
  116.    void    curson()           turns on hardware cursor
  117.    void    def_prog_mode()    save TTY modes
  118.    void    def_shell_mode()   compatibility dummy
  119. *  int     delch()            delete a char in stdscr
  120. *  int     deleteln()         delete a line in stdscr
  121. *  void    delwin(win)        delete a window or a subwindow
  122.    void    doupdate()         update physical screen
  123. *  void    echo()             set terminal echo mode
  124. *  int     endwin()           cleanup and curses finitialization
  125. *  void    erase()            erase stdscr
  126.    int     erasechar()        return char delete character
  127.    int     fixterm()          dummy for compatibility
  128.    void    flash()            flash terminal screen
  129.    void  flushinp()           kill pending keyboard input
  130. *  int     getch()    (#def macro)    get character via stdscr
  131. *  int     getstr(buf)        get string via stdscr to a buffer
  132. *  void    getyx(win,y,x)     get a window's cursor position
  133. *  int     gettmode()         dummy for compatibility
  134.    void    idlok(win,bf)      dummy for compatibility
  135. *  int     initscr()          curses initialization (ret 1 if OK)
  136. *  int     inch()             get char at stdscr cursor
  137. *  int     insch(ch)          insert character in stdscr
  138.    int     insrawch(ch)       insert raw character in stdscr
  139. *  int     insertln()         insert an empty line in stdscr
  140.    void    keypad(win,bf)     marks a window for keypad usage
  141.    int   killchar()           return line delete character
  142. *  void    leaveok(win,bf)    marks window for cursor 'update leave'
  143. *  char *longname()           returns terminal description string
  144.    void  meta(win,bf)         marks window for meta (dummy function)
  145. *  int     move(y,x)          move cursor in stdscr
  146. *  int     mvaddch(y,x,ch)        move & put char in stdscr
  147.    int     mvaddrawch(y,x,ch)     move & put raw char in stdscr
  148. *  int     mvaddstr(y,x,str)      move & put string in stdscr
  149. *  int     mvclrtobot(y,x)        move & clear end of stdscr
  150. *  int     mvclrtoeol(y,x)        move & clear lineend in stdscr
  151. *  int     mvcur(oldy,oldx,y,x)   move terminal cursor to <y,x>
  152. *  int     mvdelch(y,x)           move & delete a char in stdscr
  153. *  int     mvdeleteln(y,x)        move & delete a line in stdscr
  154. *  int     mvgetch(y,x)           move & get char to stdscr
  155. *  int     mvgetstr(y,x,buf)      move & get string via stdscr to buffer
  156. *  int     mvinch(y,x,)           move & get char at stdscr cursor
  157. *  int     mvinsch(y,x,ch)        move & insert char in stdscr
  158.    int     mvinsrawch(y,x,ch)     move & insert raw char in stdscr
  159. *  int     mvinsertln(y,x)        move & insert new line in stdscr
  160. *  int     mvprintw(y,x,fmt,args)     move & print string in stdscr
  161. *  int     mvscanw(y,x,fmt,args)      move & get values via stdscr
  162. *  int     mvwaddch(win,y,x,ch)       move & put char in a window
  163.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  164. *  int     mvwaddstr(win,y,x,str)     move & put string in a window
  165. *  int     mvwclrtobot(win,y,x)       move & clear end of a window
  166. *  int     mvwclrtoeol(win,y,x)       move & clear lineend in a window
  167. *  int     mvwdelch(win,y,x)          move & delete a char in a window
  168. *  int     mvwdeleteln(win,y,x)       move & delete a line in a window
  169. *  int     mvwgetch(win,y,x)          move & get char to a window
  170. *  int     mvwgetstr(win,y,x,str)     move & get string to a window
  171. *  int     mvwinch(win,y,x)           move & get char at window cursor
  172. *  int     mvwinsch(win,y,x,ch)       move & insert char in a window
  173.    int     mvwinsrawch(win,y,x,ch)    move & insert raw char in a window
  174. *  int     mvwinsertln(win,y,x)       move & insert new line in window
  175.    int     mvwin(win,y,x)             move window on physical screen
  176. *  int     mvwprintw(win,x,y,fmt,args)    move & print string in a window
  177. *  int     mvwscanw(win,y,x,fmt,args) move & get values via a window
  178. *  WINDOW *newwin(lines,cols,begy,begx)   create a new window
  179. *  void    nl()               set terminal cr-crlf mapping mode
  180. *  void    nocbreak()         unset terminal cbreak mod
  181. *  void    nocrmode()         unset terminal cbreak mode
  182.    void    nodelay(win,bf)    marks window for no input wait
  183. *  void    noecho()           unset terminal echo mode
  184. *  void    nonl()             unset terminal cr-crlf mapping mode
  185. *  void    noraw()            unset raw terminal mode
  186. *  void    overlay(win1,win2)     overlay one window on another
  187. *  void    overwrite(win1,win2)   overwrite one window on another
  188. *  int     printw(fmt,args)       print string in stdscr
  189. *  void    raw()                  set raw terminal mode
  190.    void    refrbrk(bf)            set screen update break mode
  191. *  void    refresh()              refresh stdscr
  192.    int     resetterm()            dummy for compatibility
  193. *  int     resetty()              restore terminal I/O modes
  194.    void    reset_prog_mode()      restore terminal I/O modes
  195.    void    reset_shell_mode()     set terminal to default modes
  196.    int     saveoldterm()          dummy for compatibility
  197.    int     saveterm()             dummy for compatibility
  198. *  int     savetty()              save terminal I/O modes
  199. *  int     scanw(fmt,args)        get values via stdscr
  200. *  void    scroll(win)            scroll scrolling region of a window
  201. *  void    scrollok(win,bf)       marks a window to allow scroll
  202.    int     setsrcreg(miny,maxy)   define stdscr's scroll region
  203. *  int     setterm()              dummy for compatibility
  204.    int     setupterm(term,fd,errret)  set up terminal (no-op on PC)
  205. *  void    standend()             start normal chars in stdscr
  206. *  void    standout()             start standout chars in stdscr
  207. *  WINDOW *subwin(win,lines,cols,begy,begx) create a sub-window in window win
  208.    int     tabsize(ts)            set/get tabsize of stdscr
  209. *  void    touchwin(win)          mark a window as totally modified
  210. *  char   *unctrl(ch)             char-to-string converter
  211.    int     ungetch(ch)    (#def macro)    push back a character to input */
  212. *  int     waddch(win,ch)         put char in a window
  213.    int     waddrawch(win,ch)      put raw char in a window
  214. *  int     waddstr(win,str)       put string in a window
  215.    void    wattroff(win,attrs)    clear attribute(s) in window
  216.    void    wattron(win,attrs)     add attribute(s) in window
  217.    void    wattrset(win,attrs)    set window char attributes
  218.    void    wborder(win,l,r,t,b,tl,tr,bl,br) Set non-std box characters
  219. *  int     wbox(win,miny,minx,maxy,maxx,l,r) draw a box inside a window
  220. *  void    wclear(win)            clear a window
  221. *  int     wclrtobot(win)         clear end of a window
  222. *  int     wclrtoeol(win)         clear end of line in a window
  223. *  int     wdelch(win)            delete a char in a window
  224. *  int     wdeleteln(win)         delete a line in a window
  225. *  void    werase(win)            erase a window
  226. *  int     wgetch(win)            get char via a window
  227. *  int     wgetstr(win,buf)       get string via window to a buffer
  228. *  int     winch(win)             get char at window cursor
  229. *  int     winsch(win,ch)         insert character in a window
  230.    int     winsrawch(win,ch)      insert raw character in a window
  231. *  int     winsertln(win)         insert new line in a window
  232. *  int     wmove(win,y,x)         move cursor in a window
  233.    void    wnoutrefresh(win)      create internal screen image
  234. *  int     wprintw(win,fmt,args)  print string in a window
  235. *  void    wrefresh(win)          refresh window
  236. *  int     wscanw(win,fmt,args)   get values via a window
  237.    int     wsetsrcreg(win,miny,maxy)  define a window's scrolling region
  238. *  void    wstandend(win)         start normal chars in window
  239. *  void    wstandout(win)         start standout chars in window
  240.    int     wtabsize(win,ts)       set/get tabsize of a window
  241.    int     wungetch(ch)           push back a character to input */
  242.  
  243. MISSING FUNCTIONS
  244.  
  245.    The following functions existing in UNIX curses are missing in PCcurses:
  246.  
  247.    getcap(nam)                    get terminal capability 'name'
  248.  
  249. FUNCTIONS UNIQUE TO PCcurses
  250.  
  251.    The following functions are (to the author's knowledge) unique to
  252.    PCcurses:
  253.  
  254.    int     addrawch(ch)           put raw char in stdscr
  255.    int     waddrawch(win,ch)      put raw char in a window
  256.    int     mvaddrawch(y,x,ch)     move & put raw char in stdscr
  257.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  258.    int   insrawch(ch)             insert raw character in stdscr
  259.    int   winsrawch(win,ch)        insert raw character in a window
  260.    int     mvinsrawch(y,x,ch)     move & insert raw char in stdscr
  261.    int     mvwinsrawch(win,y,x,ch)    move & insert raw char in a window
  262.    int   tabsize(ts)              set/get tabsize of stdscr
  263.    int     wtabsize(win,ts)       set/get tabsize of a window
  264.  
  265. SEE ALSO
  266.    "Screen Updating And Cursor Movement Optimization: A Library Package" -
  267.    Kenneth C.R.C. Arnold
  268.    "The Ncurses Reference Manual" - Pavel Curtis, Cornell University
  269.  
  270. BUGS
  271.    The terminal raw I/O mode is implemented by reading characters directly
  272.    from the BIOS. This means that the programmer must not use the normal
  273.    I/O routines to the screen or from the keyboard, since they will trap
  274.    the MS-DOS ^C, ^S, ^Q and ^P characters and thus nullify the raw input.
  275.  
  276.    Also, if the terminal is in normal or cbreak mode and the programmer has
  277.    trapped CTRL-BREAK by using signal(SIGINT,ownhandler), MS-DOS will still
  278.    echo the characters '^C' on the screen when the character is
  279.    intercepted. There seems to be no way to avoid this under MS-DOS (use
  280.    raw mode instead, or redraw the whole screen).
  281.  
  282.    The function key support is hardware dependent. There is a table in
  283.    charget.c that maps keyboard scan codes from the keyboard to function
  284.    key names. The one supplied works for IBM PC/XT/AT, and for most clones.
  285.  
  286. REVISION
  287.    The current revision is v.1.3 (881005). If you find or correct bugs, or
  288.    if you think up or implement enhancements, please contact the author.
  289.    That way he can maintain an 'official' version of PCcurses, without too
  290.    many local versions floating around.
  291.  
  292. AUTHOR
  293.    Home:     Bjorn Larsson        Work:   INFOVOX AB
  294.              Ynglingagatan 5,IV           Box 2503
  295.              S-113 47 Stockholm           S-171 02 Solna
  296.              SWEDEN                       SWEDEN
  297.  
  298.              UseNet: ...!seismo!mcvax!enea!infovax!bl
  299.